Printing Objects (IM: XOv)

Inside Macintosh: QuickDraw GX Programmer's Overview / Part 1 - Getting Started With QuickDraw GX: Chapter 3 - Using QuickDraw GX Objects

Printing Objects
In the same way that the shape object is the main object type for graphics, the job object is the main object type used for printing. A job object represents all
the printing-related information for a single document.
Figure 3-34 shows a job object and its properties.
Figure 3-34 A job object and its properties

Altogether, there are eight types of printing-related objects, and they are
as follows:

The job object represents a print job that controls the way a document is printed. The job object stores some information, such as the page range to
be printed, in its own properties. It uses a job collection object to store other information. The job object also references a list of format objects, which represent the different formats used to print the document.
The job collection object stores extra information relevant to a print job, such as the number of copies to print, how to collate copies, and so on.
The format object specifies how a document (or specified pages of a document) should be formatted. Like the job object, the format object stores some information, such as the page orientation, in its own properties. It uses a format collection object to store other information. The format object also contains a reference to a paper-type object, which represent the dimensions of the paper onto which the page is to be printed.
The format collection object stores extra information related to a page format, such as the orientation of the page.
The paper-type object specifies the physical size and the printable area of a paper type. Paper-type objects also use collection objects to store extra information.
The paper-type collection object stores extra information related to the dimensions of a paper type, such as the units used to measure the paper.
The printer object represents the characteristics of a printer. These character-
istics are set by the printer driver. You can use this object to determine these characteristics, such as the printer name, the printer type, the printer driver name, and so on. You may not change these characteristics.
The print-file object represents the file that QuickDraw GX creates as the document is spooled. A special kind of print file is the portable digital document. You can use print-file objects to determine information about
a print file, such as the file's page count.

Figure 3-35 shows the relationships between all of the printing-related objects.
Figure 3-35 The printing-related objects

Note
Before you can use any QuickDraw GX printing features, your application must call the GXInitPrinting function. You should call this function when initializing your application, immediately after creating a graphics client heap. Once you've called this function, you cannot call any Macintosh Printing Manager functions until you exit from QuickDraw GX printing using the GXExitPrinting function, which you typically do only when closing your application.
You create a job object using the GXNewJob function whenever the user of your application creates a new document. When the user saves the document, you can flatten the information in the job object using either the GXFlattenJob function or the GXFlattenJobToHdl function and then save the printing information along with the document, in either its data or resource fork.
When the user closes the document, you can dispose of the job object using the GXDisposeJob function. If the user reopens the document, you can use the GXUnflattenJob function or the GXUnflattenJobFromHdl function to restore the job object from the flattened information you saved with the document.
When the user chooses the Page Setup menu command from the File menu, your application can use the GXJobDefaultFormatDialog function to display the Page Setup dialog box, as shown in Figure 3-36.
Figure 3-36 The Page Setup dialog box

Similarly, when the user chooses the Print menu command from the File menu, your application can use the GXJobPrintDialog function to display the Print dialog box, shown in Figure 3-37.
Figure 3-37 The Print dialog box

To process update events while these dialog boxes are active, your application must call the GXInstallApplicationOverride function. This function allows you to install a message-handling function that QuickDraw GX calls in response to events that occur while the user is making selections from the dialog boxes. You can find more information about messages in Inside Macintosh: QuickDraw GX Environment and Utilities as well as Inside Macintosh: QuickDraw GX Printing.
When the user requests to print the document, you use

the GXGetJobPageRange function to find the user-specified page range
the GXStartJob function to begin printing the document
the GXPrintPage function to print the document page by page--if you have collected the pages into picture shapes; if not, you can use the functions GXStartPage, GXDrawShape (multiple times), and GXFinishPage to print your pages as collections of individual shapes.
the GXFinishJob function to inform QuickDraw GX that the document is ready to be queued for printing

For some examples of printing with QuickDraw GX, see Chapter 8, "Printing," in this book.